PrePoMax Python API Overview

This document is a simple overview of the Python API objects exposed by PrePoMax. The root object available in the Python console is pmx.

General conventions

• pmx is the root PrePoMaxAPI object.
• API objects implement help(), which prints documented members to the console.
• Collection-like objects usually support len(...), indexing with [...], and in checks.
• Ordered object collections provide first() and last() convenience methods.
• Name collections return StringList objects. ID collections return IntList objects.
• Long API arrays and named collections are shortened when evaluated directly. Use print(array) to display every item.
• Result names are strings. In many projects they are full file paths and are used to select the current result.
• Result data is exposed through pmx.results.current. Use set_current(result_name) to change it.
• Result steps and increments are indexed by result IDs, not by model step names.
• Field result data is node-based. Only history output can contain integration point values.
• Integration point history entry names use the form elementId_intPointId.
• NumPy is optional. Where available, numeric arrays are returned as NumPy arrays. Otherwise, NumericArray or typed API list wrappers are returned.
• Methods that construct Python-side drafts or specifications start with create_ and do not modify PrePoMax.
• Collection add(...) methods perform validation and make the command-recorded database change.

Script execution and regeneration

• Run script and Run selection execute in the shared interactive Python scope. State-changing API calls are recorded as individual PrePoMax commands.
• Record and Run stores the complete editor source as one phase-neutral history command and then executes it. Commands invoked by that script still use the normal controller command path, but they are not added to history a second time.
• Recorded scripts run in a fresh scope containing a new pmx, __name__ = "__main__", and __file__ = "<string>". They cannot depend on variables or imports left in the interactive console by earlier work.
• A recorded script is added to history only when it completes without an error. Full-history regeneration executes the embedded source at the same position in history; phase-only regeneration skips recorded scripts.

Typical access path

pmx
pmx.results
result_names = pmx.results.get_names()
pmx.results.set_current(result_names[-1])
result = pmx.results.current
step = result.steps[1]
increment = step.increments[1]
field = increment.fields['DISP']
component = field.components['U1']
data = component.get_data()
node_id = int(data.ids[0])
value = component.get_value(node_id)

Common API base

BaseAPI

Base class for user-facing API objects.

StringList

Read-only list wrapper for strings.

IntList

Read-only list wrapper for integers.

StringDoubleMap

Read-only ordered mapping from string names to floating-point values.

NumericArray

Read-only fallback for numeric arrays when NumPy is unavailable.

Root API

PrePoMaxAPI

Root object exposed as pmx.

Example:

pmx
pmx.results
pmx.selection
pmx.help()

Selections

SelectionFactory

pmx.selection creates selection drafts that are independent of the live UI selection. The view is required and remains stored in the selection so command replay uses the correct mesh.

Possible view values are "geometry", "femodel", and "results".

Possible target values are "nodes", "elements", "surfaces", "edges", "parts", and "geometry". Possible source values are "nodes", "elements", "vertices", "edges", "surfaces", and "parts".

Nodes, elements, vertices, and parts use a list of IDs. Vertex IDs are the node IDs displayed by Query. Edge and surface IDs are 1-based within each part and use a part-to-ID mapping:

selection = pmx.selection.create_by_ids(
    view="results",
    target="nodes",
    source="edges",
    ids={3: [1, 2], 7: [4]}
)

selection.add_by_ids(source="vertices", ids=[10282])
pmx.selection.highlight(selection)

Supported conversions:

Selection

Results collection

Results

Collection of loaded result files.

Example:

names = pmx.results.get_names()
result = pmx.results.set_current(names[-1])
# Equivalent after selection:
result = pmx.results.current

Result

Single loaded result file.

Example:

result.name
result.steps
result.mesh
result.history_outputs
result.field_outputs
node_id = int(result.mesh.nodes.get_ids()[0])
coordinates = result.get_nodal_coordinates(node_id)
deformed_coordinates = result.get_deformed_nodal_coordinates(1, 1, node_id)
value = result.get_nodal_value(1, 1, 'DISP', 'U1', node_id)

Result field output definitions

FieldOutputFilter

Immutable Python filter specification used while creating result field outputs.

FieldOutputs

Collection of user-defined result field outputs. These are postprocessing definitions that generate derived fields.

based_on is required and must be "parts", "element_sets", or "all_elements". item_limits must be a non-empty Python dictionary with finite, nonzero values. Its keys are part names, element-set names, or the single key "All elements" when based_on="all_elements".

Creation only produces a Python-side draft and does not call the controller or modify command history. Assign optional filters to the draft, then call add(output). The complete draft is converted and validated before the postprocessing command is created. If the current result changes after a Result object was obtained, get pmx.results.current again before adding the draft.

Filter creation is available directly on pmx.results.field_outputs and result.field_outputs. The filter source must be "all_nodes" or "surface_nodes"; layers and iterations must both be at least 1.

One limit for all elements:

result = pmx.results.current

output = result.field_outputs.create_field_output_limit(
    name="Stress_limit",
    field_name="STRESS",
    component_name="MISES",
    based_on="all_elements",
    item_limits={"All elements": 235.0}
)

limit_output = result.field_outputs.add(output)

One limit with two filters:

output = result.field_outputs.create_field_output_limit(
    name="Filtered_stress_limit",
    field_name="STRESS",
    component_name="MISES",
    based_on="all_elements",
    item_limits={"All elements": 235.0}
)

output.filter1 = pmx.results.field_outputs.create_median_filter(
    source="surface_nodes",
    layers=2
)
output.filter2 = pmx.results.field_outputs.create_smooth_filter(
    iterations=3
)

filtered_output = result.field_outputs.add(output)

Different limits by part:

output = result.field_outputs.create_field_output_limit(
    name="Stress_limits_by_part",
    field_name="STRESS",
    component_name="MISES",
    based_on="parts",
    item_limits={
        "Part-1": 235.0,
        "Part-2": 180.0
    }
)

limit_output = result.field_outputs.add(output)

Envelope across all result increments:

output = result.field_outputs.create_field_output_envelope(
    name="Stress_envelope",
    field_name="STRESS",
    component_name="MISES"
)
result.field_outputs.add(output)

Equation with the generated component VALUE:

output = result.field_outputs.create_field_output_equation(
    name="Normalized_stress",
    equation="=STRESS.MISES / 235.0",
    unit="/"
)
result.field_outputs.add(output)

Coordinate-system transform:

output = result.field_outputs.create_field_output_coordinate_system_transform(
    name="Local_stress",
    field_name="STRESS",
    coordinate_system_name="Local_CS"
)
result.field_outputs.add(output)

Replace an existing definition:

replacement = result.field_outputs.create_field_output_limit(
    name="Stress_limit",
    field_name="STRESS",
    component_name="MISES",
    based_on="all_elements",
    item_limits={"All elements": 250.0}
)

result.field_outputs.replace("Stress_limit", replacement)

Remove definitions or stored fields and components:

result.field_outputs.remove(["Stress_limit", "Old_field"])
result.field_outputs.remove_components("DISP", ["U3"])

Export every component of a field at one increment to a file:

result.field_outputs.export_to_csv(
    file_name=r"C:\Temp\Stress_limit.csv",
    field_output_name="Stress_limit",
    step_id=1,
    increment_id=1
)

FieldOutputDraft

Python-side field-output definition that has not yet been added to the result.

filter2 cannot be used unless filter1 is also assigned.

FieldOutputLimitDraft

Limit field-output draft returned by create_field_output_limit.

FieldOutputEnvelopeDraft

Envelope draft returned by create_field_output_envelope. It produces MAX, MIN, and AVERAGE components.

FieldOutputEquationDraft

Equation draft returned by create_field_output_equation.

FieldOutputCoordinateSystemTransformDraft

Coordinate-system transform draft returned by create_field_output_coordinate_system_transform.

FieldOutput

Base representation of a user-defined result field output.

FieldOutputLimit

Limit-based field output returned by add(output) or collection lookup.

FieldOutputEnvelope

FieldOutputEquation

FieldOutputCoordinateSystemTransform

Steps and increments

Steps

Collection of result steps.

Step

Single result step.

Increments

Collection of increments inside a result step.

Increment

Single result increment.

Field results

Field result data is node-based. The returned IDs are node IDs.

Fields

Collection of field outputs for one increment.

Field

Single field output, such as displacement, stress, or temperature.

FieldComponents

Collection of field components.

FieldComponent

Single scalar component of a field result.

FieldData

Node-based scalar field component data.

Example:

disp = increment.fields['DISP']
u1 = disp.components['U1'].get_data()
u1.ids
u1.values

FieldMultiComponentData

Node-based data for all components of a field.

Example:

data = increment.fields['DISP'].get_data()
data.component_names
data.values

Mesh

Mesh

Mesh associated with a result.

Nodes

Collection of mesh nodes.

NodeData

Undeformed node coordinate data.

Elements

Collection of mesh elements.

Element

Single mesh element.

Example:

element = result.mesh.elements[10]
element.node_ids

ElementData

Bulk element connectivity data.

offsets are needed only when reading the flattened connectivity array directly. For element index i, its node IDs are stored in:

connectivity[offsets[i]:offsets[i + 1]]

For normal use, prefer:

node_ids = result.mesh.elements.get_node_ids(element_id)
# or
node_ids = result.mesh.elements[element_id].node_ids

Parts

Collection of mesh parts.

Part

Single mesh part.

Read-only result regions

Node sets, element sets, and surfaces are copied from the model into the result mesh. They can be inspected and used by result history outputs, but they cannot be created, changed, or removed through the results API.

The node_sets, element_sets, and surfaces collections support indexing by name, len(), get_names(), first(), last(), and contains(name).

Example:

node_set = result.mesh.node_sets["Node_Set-1"]
element_set = result.mesh.element_sets["Element_Set-1"]
surface = result.mesh.surfaces["Surface-1"]

History results

History outputs can contain node, element, or integration point values depending on the output definition. Integration point entries use names like elementId_intPointId.

HistoryOutputs

Collection of result history outputs.

Creation examples:

result = pmx.results.current

nodes = pmx.selection.create_by_ids(
    view="results",
    target="nodes",
    source="edges",
    ids={3: [1, 2]}
)

output = result.history_outputs.create_history_output_from_field(
    name="Edge_DISP",
    field_name="DISP",
    component_names=["U1", "U2", "U3"],
    region=nodes
)
output.step_id = None
output.increment_id = None
output.filter1 = result.history_outputs.create_average_filter(operate_on="rows")
output.filter2 = result.history_outputs.create_maximum_filter(return_value="row")
result.history_outputs.add(output)

Existing result regions are passed directly through the same region argument:

output = result.history_outputs.create_history_output_from_field(
    name="Node_set_DISP",
    field_name="DISP",
    component_names=["U1"],
    region=result.mesh.node_sets["Node_Set-1"]
)
result.history_outputs.add(output)

output = result.history_outputs.create_history_output_from_equation(
    name="Energy_sum",
    equation="Energy_1 + Energy_2",
    unit="J"
)
result.history_outputs.add(output)

Line integration integrates a field over geometry edges (works for both shell and solid parts). For 2D output (plane stress/strain or axisymmetric) set cross_section to apply the out-of-plane scaling; "thickness" additionally uses the thickness argument, while "axisymmetric" scales by 2*pi*r (the radial coordinate is the X coordinate):

edges = pmx.selection.create_by_ids(
    view="results",
    target="edges",
    source="edges",
    ids={1: [3, 4]}
)

output = result.history_outputs.create_history_output_from_integration(
    name="Line_Force",
    integral_type="line",
    field_name="STRESS",
    component_names=["S11"],
    region=edges,
    cross_section="thickness",
    thickness=0.01,
    unit="N"
)
result.history_outputs.add(output)

integral_result selects what the integral evaluates: "geometry" (the region size, integrating a unit field; the default), "field" (the field integral), or "field_by_geometry" (the region average of the field). "geometry" and "field" report one entry per element, so a Sum filter gives the total size and the region total; "field_by_geometry" instead sums the element integrals and the element measures over the whole region and divides the sums, so it returns a single REGION entry that is already the measure-weighted average (no Sum filter needed). field_name and component_names are not needed for "geometry". The geometry result is reported in a single SIZE component; note that the cross section scaling changes its dimension, so a scaled line integral returns an area and a scaled surface integral a volume:

output = result.history_outputs.create_history_output_from_integration(
    name="Surface_area",
    integral_type="surface",
    region=faces,
    integral_result="geometry",
    unit="mm2"
)
result.history_outputs.add(output)

create_history_output_from_merged_histories, create_history_output_from_extracted_entry, and create_history_output_xy build a new history output from history components that already exist in the result. Each source argument is either a HistoryComponent object or a list of three strings [history_output_name, field_name, component_name]:

history_output = result.history_outputs["Node_DISP"]
source = history_output.fields["DISP"].components["U1"]
same_source = ["Node_DISP", "DISP", "U1"]

Merging collects the entries of two to four history components into a single history output. All merged entries must use the same unit and must share a common reference time; entries of the later sources are interpolated to the times of the first source. Each source may be used only once:

output = result.history_outputs.create_history_output_from_merged_histories(
    name="Merged_reactions",
    source1=["Node_set_1_FORC", "FORC", "F1"],
    source2=["Node_set_2_FORC", "FORC", "F1"]
)
result.history_outputs.add(output)

Extraction copies a single named entry of a history component into its own history output. The entry must exist in the source component and must contain finite data:

component = result.history_outputs["Node_DISP"].fields["DISP"].components["U1"]
output = result.history_outputs.create_history_output_from_extracted_entry(
    name="Node_5_U1",
    source=component,
    entry_name=str(component.get_entry_names()[0])
)
result.history_outputs.add(output)

An XY output replaces the time axis with the values of another history component. The X component must contain exactly one entry, all entries of the Y component must use the same unit, and both sources must share a common reference time:

output = result.history_outputs.create_history_output_xy(
    name="Force_vs_displacement",
    x_source=["Node_DISP", "DISP", "U1"],
    y_source=["Node_FORC", "FORC", "F1"]
)
result.history_outputs.add(output)

A table output needs no result data at all. The number of Y columns is taken from the row length, all rows must contain the same number of values, every value must be finite, and the Y-column names must be unique. When y_column_names is omitted, the columns are named Y1, Y2, ...:

output = result.history_outputs.create_history_output_from_table(
    name="Measured_curve",
    data_points=[[0.0, 0.0, 0.0], [1.0, 12.5, 11.0], [2.0, 24.0, 23.5]],
    y_column_names=["Test_1", "Test_2"],
    x_axis_unit="mm",
    y_axis_unit="N"
)
result.history_outputs.add(output)

All four output types produce a single Table.Values field component whose entries are the Y columns, and they accept filter1/filter2 like every other history-output draft.

The supported region combinations are:

Possible deformation variable names are "Displacements", "Forces", "Surface Normals", "Wear Depths", "Mesh Deformation", "Disp&Def", and "Disp&Def&Depth".

HistoryOutputFilter

Immutable Python filter specification assigned to filter1 or filter2 on any history-output draft. Filters are applied in order, and filter2 cannot be used without filter1.

HistoryOutputDraft

Base object for history-output definitions that have not yet been added to the result.

HistoryOutputFromMergedHistoriesDraft

From Merged Histories draft. Adds to HistoryOutputDraft:

HistoryOutputFromExtractedEntryDraft

From Extracted Entry draft. Adds to HistoryOutputDraft:

HistoryOutputXYDraft

XY draft. Adds to HistoryOutputDraft:

HistoryOutputFromTableDraft

From Table draft. Adds to HistoryOutputDraft:

HistoryOutput

Base representation of a history output. The history_outputs collection holds both the history outputs produced by the solver and those defined by the user, so is_user_defined tells the two apart. Looking a user-defined output up by name returns the matching type-specific object below; solver-generated outputs and From Affine Fit outputs return this base object.

Reading a definition back:

history_output = result.history_outputs["Edge_DISP"]
if history_output.is_user_defined and history_output.type_name == "ResultHistoryOutputFromField":
    print(history_output.field_name, list(history_output.component_names), history_output.region_type)

HistoryOutputFromField

HistoryOutputFromEquation

HistoryOutputFromIntegration

HistoryOutputFromMergedHistories

HistoryOutputFromExtractedEntry

HistoryOutputXY

HistoryOutputFromTable

HistoryFields

Collection of history fields.

HistoryField

Single history field.

HistoryComponents

Collection of history components.

HistoryComponent

Single history component.

HistoryEntries

Collection of named history entries.

HistoryEntry

Single named history entry.

HistoryComponentData

History data returned from a complete history component.

HistoryEntryData

History data for one selected entry.

Example:

history_names = result.history_outputs.get_names()
history_output = result.history_outputs[history_names[0]]
field = history_output.fields[history_output.fields.get_names()[0]]
component = field.components[field.components.get_names()[0]]
entry_names = component.get_entry_names()
entry = component.entries[entry_names[0]]
data = entry.get_data()

# Equivalent convenience access
entries = result.get_history_output_entries(history_names[0], field.name, component.name)
entry = result.get_history_output_entry(history_names[0], field.name, component.name, entry_names[0])

Internal and infrastructure classes

These classes exist in the implementation but are not normally used directly from the Python console.

Source Folder Layout

The Python API resides in the APIs class-library project. Its source is grouped by object area under the Python folder, with helper and data-service classes stored beside the APIs they support. All Python API classes use the flat APIs.Python namespace. PrePoMax keeps only the controller and embedded-engine host adapters.

C# classes and files use explicit names such as ResultStepAPI, ResultIncrementAPI, ResultHistoryOutputAPI, and ResultHistoryOutputFieldAPI. Python-visible names remain Step, Increment, HistoryOutput, and HistoryField.

APIs
  Python
    Commands
    Common
    Mesh
      Elements
      Nodes
      Parts
    Selection
    Results
      Fields
      ResultFieldOutputs
      ResultHistoryOutputs

PrePoMax/Python
  Commands
  Engine

Notes for documentation generation

• The [PythonAPI] attribute descriptions are the best source for generated member documentation.
• ToString() implementations provide concise expression output; print(...) uses the full display text for arrays and named collections.
• Keep implementation-only methods unmarked by [PythonAPI] if they should be hidden from help and autocomplete.
• Prefer documenting collection access with [...] because this is the intended Python style.